1


                       Program CONVERS - Installation Notes

                                   John Dykstra

                                  April 14, 1984





           This document is an attempt to describe everything needed to
           install CONVERS on a personal computer running the p-System.
           Most of  the  material  concerns  the  external  compilation
           UNIT's  that  are  used to interface CONVERS to the hardware
           and software of the system.  There is also  some  discussion
           of  the  system  features  useful  or necessary when running
           CONVERS, and some miscellaneous notes.

           The final section describes TERMINAL, which  provides  "dumb
           terminal"  emulation,  with  the  added capability of easily
           calling CONVERS.






                               John Dykstra
                               4788 Anderson Lane
                               Shoreview, MN  55112
                               (612) 483-4286
                               (612) 482-3874

























1                                                                   1-1
                                                               84/04/16
        ---------------------------------------------------------------
        1.0 SEPARATE COMPILATION UNITS

        ---------------------------------------------------------------

           1.0 SEPARATE COMPILATION UNITS
+              __________________________


           CONVERS uses separate compilation units  to  handle  machine
           and implementation dependent matters.

           1.1 SCREENOPS
+              _________

           Softech provides SCREENOPS as a standard part of the Version
           IV p-System.

           II.0 systems can use the SCREENOPS  provided  with  CONVERS.
           Since  this  UNIT  obtains  character  definitions  from the
           p-system, this code should work for all II.0 systems.   II.1
           users  may  have  to  modify it to get it to work with their
           systems.

           To compile SCREENOPS on either II.0 or II.1, you will need a
           copy  of  the  GLOBALS  definitions  for your system.  These
           files have been distributed through USUS.

           1.2 REMUNIT
+              _______

           CONVERS uses  the  USUS  standard  remote  compilation  unit
           REMUNIT to interface to the link.  See USUS Newsletter 4 for
           a description of this UNIT.  REMUNIT's for  several  popular
           personal  computers  have  been distributed through the USUS
           library.

           1.3 TEXTIO
+              ______

           TEXTIO handles reading and  writing  text  lines  from  disk
           files.   It  has two advantages: It allows ARRAY's of FILES,
           and on II.0 systems it is much faster than Pascal  READ  and
           WRITE statements.

           I  have  included sources of TEXTIO for II.0 and IV systems.
           Both should run without modification on all systems  of  the
           proper  version.   If  you have II.1, you may have to modify
           the II.0 source to get it to compile.

           The  source  for  IV  includes  explicit  p-codes,  and  may
           therefore  have  to be modified due to future changes in the
           p-System.  It has been tested thru  Version  IV.03.   If  it
           stops  working when you upgrade to a later system, try using
           DECODE to look at the p-codes generated by  READ  and  WRITE
           statements.






1                                                                   1-2
                                                               84/04/16
        ---------------------------------------------------------------
        1.0 SEPARATE COMPILATION UNITS
        1.4 OSMISC
        ---------------------------------------------------------------

           1.4 OSMISC
+              ______

           This unit provides miscellaneous services, including  a  way
           to  pass  parameters  and commands between various programs,
           and a real-time timer.

           The UCSD operating  system  currently  does  not  provide  a
           standard  way  to  pass  a  parameter string to an executing
           program.  OSMISC implements my own scheme.  The  unit  first
           looks  for  a parameter string on a file called CMDLINE.TEXT
           on the system device.  If that file does  not  exist  or  is
           empty, a command string is requested from the keyboard.

           The  EXECUTE command calls OSMISC to pass a parameter string
           to  the  called  program.   That  string   is   written   to
           CMDLINE.TEXT on the system device.

           OSMISC  also  implements  the  real-time timers that CONVERS
           uses to keep track of how long it waits for  prompts.   Time
           periods   are   expressed   in  tenths  of  a  second.   The
           distributed  versions  of  these  UNIT's   approximate   the
           operation of the timers by delay loops.  If these UNIT's are
           used, the time periods specified in  scripts  will  be  only
           approximate.   If your system has a real-time clock, you may
           want to modify OSMISC to use it.

           There are two versions of OSMISC provided.  The II.0 version
           uses  a separate unit called CHAIN from Volume 8 of the USUS
           library.  The IV version uses interfaces  from  the  Softech
           standard unit COMMANDIO.

           Both  of  these  versions  follow  their own conventions for
           keyboard control, which may or may not match the conventions
           of  your  system.   The  backspace key is used to delete one
           character, and ASCII code CAN (control-X) is used to  delete
           the  entire  typein.   If  desired,  these can be changed by
           editing and compiling the source for the unit.
















1                                                                   2-1
                                                               84/04/16
        ---------------------------------------------------------------
        2.0 OTHER SYSTEM REQUIREMENTS AND INTERFACES

        ---------------------------------------------------------------

           2.0 OTHER SYSTEM REQUIREMENTS AND INTERFACES
+              ________________________________________


           2.1 DISPLAY
+              _______

           CONVERS uses the SC_USE_INFO procedure in SCREENOPS to  find
           out  the height of the display screen.  (It assumes that the
           screen is at least 80 characters wide.)

           Separate compilation unit  OSMISC  assumes  that  the  ASCII
           character  BS  (backspace)  moves  the cursor back one space
           when written to  the  display.   This  can  be  changed,  if
           necessary, by editing and re-compiling OSMISC.

           2.2 LINK
+              ____

           CONVERS  uses  the  USUS  standard  remote  compilation unit
           REMUNIT to interface to the link.   Normally,  the  physical
           implementation  of  the link is an asynchronous RS-232 line,
           possibly including modems and dial-up connections.

           When CONVERS begins operation, it "searches" for the highest
           baud  rate  accepted  by  REMUNIT.   The following rates are
           tried, in the order given: 9600, 1200, 300 and 110 baud.  If
           none  of  these  baud  rates is accepted and the remote unit
           does not supply its own default (indicated by  a  result  of
           CR_SELECT_NOT_SUPPORTED),   a   message  is  displayed,  and
           CONVERS aborts.

           If this procedure will not work with your REMUNIT,  set  the
           constant  DEFAULT_BAUD  at  the  beginning of CONVERS to the
           baud rate  desired,  and  all  of  this  searching  will  be
           bypassed.

           CONVERS    calls    CR_SETCOMMUNICATIONS   with   parameters
           specifying even parity, a character size of 7  bits,  and  1
           stop  bit.   If necessary, these defaults can be changed via
           the constant declarations at the beginning  of  the  CONVERS
           source code.

           To   reduce  the  possiblility  of  losing  incoming  serial
           characters during workstation disk I/O operations, the  link
           hardware  should  be interrupt-driven, and provide buffering
           capacity.   The  exact  amount  of  buffering  necessary  is
           dependent  upon  the link data rate and workstation hardware
           characteristics.  CONVERS has been successfully run  at  300
           baud  with  16  characters of buffer space, and at 1200 baud
           with 64 characters of space.

           If the host system recognizes flow-control  characters  such
           as  DC1 and DC3 (sometimes referred to as XON and XOFF), the


1                                                                   2-2
                                                               84/04/16
        ---------------------------------------------------------------
        2.0 OTHER SYSTEM REQUIREMENTS AND INTERFACES
        2.2 LINK
        ---------------------------------------------------------------

           interrupt driver for the link can use this flow  control  to
           prevent   overflow   of   its   buffers.   This  effectively
           eliminates any chance of losing characters.

           If  possible,  interaction  with  the  host  should  be   in
           full-duplex  mode.   This  eliminates  the possibility of an
           echoed character appearing in the middle of  a  host  string
           that   is   being  searched  for  by  CONVERS,  and  falsely
           preventing recognition of the match.  The UPLOAD  option  of
           TRANSFER attempts to read and discard any echos it receives,
           but CONVERS has not been extensively tested in this mode.

           The CONVERS commands DIAL and HANGUP have not  been  tested,
           due to the lack of an auto-dial modem.







































1                                                                   3-1
                                                               84/04/16
        ---------------------------------------------------------------
        3.0 MISCELLANEOUS NOTES

        ---------------------------------------------------------------

           3.0 MISCELLANEOUS NOTES
+              ___________________


           The UCSD P-system permits file names to begin with  a  digit
           character.   These file names cannot be used by CONVERS, due
           to a syntatic conflict between names and integer  constants.















































1                                                                   4-1
                                                               84/04/16
        ---------------------------------------------------------------
        4.0 PROGRAM TERMINAL

        ---------------------------------------------------------------

           4.0 PROGRAM TERMINAL
+              ________________


           This program provides "dumb terminal"  emulation,  with  the
           added capability of easily calling CONVERS.

           The  baud  rate, parity, character size and stop bit options
           used by terminal are determined by  compile-time  constants.
           The code uses separate compilation units REMUNIT, SCREENOPS,
           and OSMISC.

           When TERMINAL is executed, it immediately goes into terminal
           mode.   Every  key  hit will be transmitted to the host, and
           each character received from the host is displayed.

           Hitting Control-E will exit the program.

           Hitting Control-C will result in  a  prompt  for  a  CONVERS
           parameter  string.   The  user should enter a command string
           for CONVERS, in the usual  form.   When  carriage-return  is
           hit,  TERMINAL  ends  execution,  and  CONVERS  begins.   If
           carriage-return is hit without a  parameter  line,  TERMINAL
           continues execution.








                 





















1
                                                               84/04/16

                                 Table of Contents


           1.0 SEPARATE COMPILATION UNITS  . . . . . . . . . . .    1-1
           1.1 SCREENOPS . . . . . . . . . . . . . . . . . . . .    1-1
           1.2 REMUNIT . . . . . . . . . . . . . . . . . . . . .    1-1
           1.3 TEXTIO  . . . . . . . . . . . . . . . . . . . . .    1-1
           1.4 OSMISC  . . . . . . . . . . . . . . . . . . . . .    1-2

           2.0 OTHER SYSTEM REQUIREMENTS AND INTERFACES  . . . .    2-1
           2.1 DISPLAY . . . . . . . . . . . . . . . . . . . . .    2-1
           2.2 LINK  . . . . . . . . . . . . . . . . . . . . . .    2-1

           3.0 MISCELLANEOUS NOTES . . . . . . . . . . . . . . .    3-1

           4.0 PROGRAM TERMINAL  . . . . . . . . . . . . . . . .    4-1










































